Sets the name and resource ID of a resource.

void SetResInfo (
    Handle theResource, 
    SInt16 theID, 
    ConstStr255Param name
);

theResource

A handle to the resource whose name and ID you wish to set.

theID

The new resource ID. If the parameter theResource doesn’t contain a handle to an existing resource, the function does nothing, and the ResError function returns the result code resNotFound.

name

The new name of the specified resource. If you pass an empty string for the name parameter, the resource name is not changed.

DISCUSSION

The function changes the information in the resource map in memory, not in the resource file itself. Do not change a system resource’s resource ID or name. Other applications may already access the resource and may not work properly if you change the resource ID, resource name, or both.

If the resource map becomes too large to fit in memory (for example, after an unnamed resource is given a name), this function does nothing, and ResError returns an appropriate Memory Manager result code. The same is true if the resource data in memory can’t be written to the resource fork (for example, because the disk is full). If the resProtected attribute is set for the resource, SetResInfo does nothing, and ResError returns the result code resAttrErr.

If you want to write changes to the resource map on disk after updating the resource map in memory, call the ChangedResource function for the same resource after you call SetResInfo. Even if you don’t call ChangedResource after using this function to change the name and resource ID of a resource, the change may be written to disk when the Resource Manager updates the resource fork. If you call ChangedResource for any resource in the same resource fork, or if you add or remove a resource, the Resource Manager writes the entire resource map to disk after a call to the UpdateResFile function or when your application terminates. In these cases, all changes to resource information in the resource map become permanent. If you want any of the changes to be temporary, you should restore the original information before the resource is updated.

SPECIAL CONSIDERATIONS

This function may move or purge memory blocks in the application heap. Your application should not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)